home *** CD-ROM | disk | FTP | other *** search
/ MacHack 1998 / MacHack 1998.toast / Misc / Mozilla.org / MacCVS Pro 2.1b2 / Read Me < prev   
Text File  |  1998-05-13  |  14KB  |  327 lines
  1. ------------------------------------------------------------------------------
  2.                                 About MacCVS Pro
  3.                                 
  4.                             <http://www.maccvs.org>
  5.  
  6. ------------------------------------------------------------------------------
  7.  
  8. Introduction
  9. ------------
  10.  
  11. * About MacCVS Pro
  12.  
  13. MacCVS Pro is a full-featured client for the CVS source code control
  14. system. It allows you to check in and out files to a network CVS
  15. repository as well as run other CVS commands such as CVS Log and CVS
  16. Status. In addition, MacCVS Pro is multi-threaded so you can execute
  17. multiple operations simultaneously.
  18.  
  19. MacCVS Pro was designed to be easy to use and very intuitive and does
  20. not assume the user is a software engineer or someone of similar
  21. background.
  22.  
  23. * About CVS
  24.  
  25. CVS, which stands for Concurrent Version System, is a system used for
  26. large- and small-scale software development projects, which tracks the
  27. revision history of all files in the project, allows multiple developers
  28. to work on the same source base, and allows for multiple versions of the
  29. project to be developed concurrently from the same source tree.
  30.  
  31. In CVS, the client and server usually run on different machines, and the
  32. client communicates with the server over a local area network, or the
  33. Internet. The CVS server software is available in source form, and
  34. should compile on most flavors of UNIX. 
  35.  
  36. For more information about CVS, see Cyclic's web site, at:
  37.  
  38.     <http://www.cyclic.com/cyclic-pages/overview.html>
  39.  
  40.  
  41. Installation & setup
  42. --------------------
  43.  
  44. These are intended to be introductory docs. For more detailed information,
  45. see the documentation online at <http://www.maccvs.org/>.
  46.  
  47. * Installation
  48.  
  49. MacCVS Pro simply needs to be copied onto your hard drive. All its settings
  50. are stored in the session files, so no additional files are required or
  51. created.
  52.  
  53. * Session settings
  54.  
  55. To start using MacCVS Pro on a source tree, you first need to make a
  56. session file. Run MacCVS Pro, and choose File:New to make a new
  57. session file. You will be prompted for a location to save the file;
  58. specify a name, and save the file. You will now see an empty window,
  59. which is a project view window.
  60.  
  61. Before checking out any source files, you have to specify the address
  62. of the CVS server, and some other details. Open the session settings from
  63. the Edit menu (also Command-;). There are four panels of settings here,
  64. accessible through the popup menu at the top of the dialog. The important
  65. settings are described below.
  66.  
  67.     Panel 1 "Checkout and update options"
  68.     
  69.     At the top of this panel is a button used to set the root folder,
  70.     into which the source tree will go. Make a new folder in the 
  71.     Finder (say, in the same folder as the MacCVS session file you
  72.     just created), then switch back to MacCVS, click this "Set"
  73.     button and selection the folder you just made. This is where
  74.     the source tree will be created when you check out.
  75.     
  76.     The second grouping controls file merges. Use these options
  77.     to specify what happens on update when you have modified a file
  78.     locally, and someone else has also checked in changes. Most
  79.     people will want to use the "Auto Merge Text Files and Update
  80.     Binary Files".
  81.     
  82.     The next two checkboxes control the verbosity of MacCVS Pro's
  83.     output messages. When checking out a new tree, you probably
  84.     want to just output messages for directories. When updating
  85.     an existing tree, outputting messages for every file is useful
  86.     so you can see what has changed.
  87.     
  88.     Finally, the last two fields, which are very important. Here
  89.     you specify the module, or directory you want to check out,
  90.     and the revision (tag) or date you wish to check out to
  91.     (if any). The default module will either be a module name
  92.     ("MacCVSPro") or a directory path ("src/maccvs/src/"). The
  93.     default revision may be empty, if you are checking out
  94.     to the tip, or it might be a branch tag ("MacCVS202_branch").
  95.  
  96.     Panel 2 "Remote Host Information"
  97.     
  98.     This panel is used to specify the address of the CVS server,
  99.     your user name and password, and the root of the CVS tree
  100.     on the repository.
  101.     
  102.     The server hostname may be either a dotted name ("cvs.thisplace.com")
  103.     or IP addresss ("192.12.13.124"). User name is your user name
  104.     on the CVS server (which may be "anonymous" for a read-only server).
  105.     Password is your password on the server (some read-only servers
  106.     user "anonymous" here too). CVS Root specifies the root of the
  107.     source tree on the server, and will be given to you when you
  108.     get information about the CVS server. [See the section below about
  109.     interpreting UNIX-type CVS environment settings.]
  110.  
  111.     The CVS command is only applicable when using RSH to talk to 
  112.     the server; that option is not covered here. See the online
  113.     docs for more information.
  114.     
  115.     Finally, there is a field you can use to adjust the amount of
  116.     time MacCVS waits before giving up on a connection. You might
  117.     want to increase this on a busy server, or slow connection.
  118.  
  119.     Panel 3 "Encoding and file mappings"
  120.     
  121.     These settings determine what file types will be used for files
  122.     that MacCVS Pro creates. You can probably leave these alone
  123.     unless you are using a development environment other than
  124.     Metrowerks CodeWarrrior.
  125.     
  126.     Panel 4 "Miscellaneous"
  127.     
  128.     The first two checkboxes control the behaviour of the message
  129.     window. Check the "Automatically clear message window" box to
  130.     wipe out all message for each new operation. "Scroll to new messages"
  131.     is obvious, can can slow down things a bit. The contents of the
  132.     "New Folder Properties" panel are not yet implemented.
  133.     
  134. * Interpreting UNIX-type CVS environment settings
  135.     
  136.     CVS settings are often specified for UNIX or Windows users,
  137.     and are given as something like:
  138.         
  139.         :pserver:anonymous@cvs1.mozilla.org:/cvsroot
  140.         
  141.     In MacCVS Pro-speak, that translates to:
  142.         1.    Use pserver authentication (the only sort that MacCVS Pro
  143.             supports at the moment).
  144.         2.    Username is "anonymous" (without the quotes). The password
  145.             will also be specified separately, so you will have to enter
  146.             that as well.
  147.         3.     The server address is cvs1.mozilla.org.
  148.         4.     The CVS root is /cvsroot (leading / is important!).
  149.     
  150.     The instructions then probably say something like "checkout the
  151.     module xyz", or, on the command line, "cvs checkout xyz". So
  152.     "xyz" is what you enter in the Default Module box.
  153.     
  154.     If checking out to a particular tag:
  155.         cvs checkout xyz -r bugfix_branch
  156.     then you enter "bugfix_branch" in the Default revision box.
  157.  
  158. * Checking out
  159.  
  160. Now you have the session settings set up, it's a good time to save the
  161. session file. All those settings are stored in the session file, as well
  162. as any other tags that you use for updating individual files.
  163.  
  164. So, to check out the entire source tree, go Action:Check out default module
  165. (Command-;). This gets the server to report which directories are in the
  166. default module (as specified in the session settings), and checks out those
  167. to your local disk. This can take some time, and eat up considerable amounts
  168. of disk space, depending on the size of the tree.
  169.  
  170. Congratulations! Now you have checked out the source tree, and can
  171. start to work on the code. You will notice that Codewarrior recognizes
  172. that files checked out in this way are read-only, and when you try
  173. to edit them for the first time, you have to make them writable. You
  174. can do this either from MacCVS Pro (Action:Modify read-only, Command-M)
  175. or in Codewarrior with the version control popup in the sourc window.
  176.  
  177. * Updating & merging
  178.  
  179. So you've edited a few files, and checked that they compile. Before you
  180. check in, you might want to update your local tree, to get any other changes
  181. that others have made since you checked out. You can either selection, and
  182. update specific directories in MacCVS Pro, or simply do a Check out defalt
  183. module again. If you want new changes merged into your modified files, 
  184. ensure that one of the 'Auto merge text files' options is turned on
  185. in the session settings. Binary files (e.g. GIF files, or resource files)
  186. cannot be merged, for obvious reasons, but MacCVS Pro updates them by
  187. copying your modified version to a ~0 file, and checking out the new
  188. version.
  189.  
  190. If both you and someone else have edited the same line in a source file,
  191. then you may get merge conflicts. These will show up as a message with a
  192. red warning icon. Merge conflicts must be resolved before you can check
  193. in. Double-click the conflict message to show the bad file, and double
  194. click the file to open it in CodeWarrior. A 'Make' will usually quickly
  195. show you where the conflicts are.
  196.  
  197. * Checking in
  198.  
  199. Once you have resolved any merge conflicts, and are sure that your
  200. changes build, you can check in. You can either simply show and
  201. select your modified files in the project view windows (the Finder-like
  202. views of your files), or you can use the Find Lurkers command to 
  203. list all new and modified files. In either case, select those files
  204. that you want to check in, and use the Action:Commit menu command.
  205. You will be asked for a checkin comment, and can select to use just
  206. one comment for all files, or separate ones for each. Type in
  207. a sensible command, and hit the Commit button. All being well,
  208. the CVS server should send back responses that the commit was
  209. successful, and the version number of the file will be updated.
  210.  
  211. * Gotchas
  212.  
  213. MacCVS is very careful about thread safetly and potential file
  214. corruption, and thus prevents some operations on source files which
  215. are open elsewhere. While updating or checking out, you must close
  216. any open files in CodeWarrior or other editors which are in the
  217. tree being updated, and you must close source files before committing
  218. them. If you see a -49 error message, it usually means that a file
  219. is open in some other application.
  220.  
  221. * Other useful commands
  222.  
  223. It's always a good idea to diff files you are about to check in, to
  224. make sure that you know what is going into the repository. MacCVS Pro
  225. has two commands to do this: Status:Diff, which shows UNIX-style
  226. diff output, and Status:Compare with original, which shows a more
  227. useful view of the source using colors to hilight new, changed and
  228. removed lines.
  229.  
  230. To add a new file or folder to the repository, use the Action:Add menu
  231. command. Added files automatically get the checkin comment "First checked
  232. in". Be careful when adding new files to choose the right file type;
  233. source files should be added as TEXT, resource files as AppleSingle, and
  234. other files (e.g. GIF files, SIT archives) as binary. Some attempt is made
  235. to set the default to the correct one.
  236.  
  237. * Interoperability with other CVS clients
  238.  
  239. Due to the different way in which MacCVS Pro stores revision and other
  240. information, source trees checked out using MacCVS Pro cannot be safely
  241. used with other Macintosh CVS clients, and vice versa. You should stick
  242. to using a single client on your source tree. This additional information
  243. permits increased functionality and optimization in our client, so we
  244. believe this to be worthwhile.
  245.  
  246. Known bugs & Limitations
  247. ------------------------
  248.  
  249. We know of no crashing bugs in MacCVS Pro.
  250.  
  251. The UI still needs some fine-tuning, and could do with a little more
  252. functionality in project views (e.g. resizing columns). There are some
  253. minor refresh problems here too.
  254.  
  255. * Other known bugs:
  256.     Pressing the "Stop" button while decoding an AppleSingle file will bring
  257.     up an "Error 700" message in the message window. This is harmless.
  258.     
  259.     If you select thousands of items, MacCVS will slow down to a halt.
  260.     
  261.     There is a bug in Find Lurkers where it won't find some modified files.
  262.     This only happens if you're running a Find Lurkers operation on
  263.     directory that already has some CVS operation (ie. checkout/update)
  264.     running on it. I don't know what the deal is here yet.
  265.     
  266.     If you open a non-modified, non-MROed, file with Resourcer 2.0 it will
  267.     ask you if you want to open the file read only. If you choose the modify
  268.     the file, Resourcer will update the ckid with a bad checksum! Simply
  269.     open the 'ckid' resource, type in 0 for the checksum, close the resource
  270.     and save the file. That should clear up the problem.
  271.     
  272.     Trying to commit a file that actually hasn't changed will fail. However,
  273.     the CVS server never sends an error message so you never get any
  274.     feedback that your operation has failed.
  275.     
  276.     The project views do not update folder tags and other attributes if the
  277.     folder is collapsed.
  278.     
  279.     Drag selecting any of the TE fields sometimes does weird things. This is
  280.     not a bug in MacCVS, but a problem in the PowerPlant LTextEditView
  281.     class.
  282.     
  283.     Due to the poorly specified cvs server protocol, there are some problems
  284.     with operations on files in the root directory, and when using alias
  285.     directories (server-side aliases, that is).
  286.  
  287. * Limitations
  288.  
  289.     pserver is the only authenticaion protocol currently supported
  290.     
  291.     Won't work with really old CVS servers (pre 1.5)
  292.     
  293.     Trees checked out with MacCVS Pro can't be used with other Macintosh
  294.     CVS clients
  295.     
  296.     File names > 29 chars cause an error (This is a limitation of the Mac
  297.     file system and is not a MacCVS bug. Such files are simply ignored,
  298.     and do not interrupt the checkout process.)
  299.     
  300.     No command line, not all CVS client operations supported (at present).
  301.     
  302.     No gzip support (i.e. the equivalent of cvs -z9 checkout is not available).
  303.  
  304. Version history
  305. ---------------
  306.  
  307. 2.1b2    12 May 1998
  308.  
  309. Fixed a problem with Find Lurkers, which caused new files without resource
  310. forks not to show up in the lurkers list.
  311.  
  312. Fixed a problem when committing files using keywords, which caused the
  313. file not to be updated in your local tree.
  314.  
  315. Some minor window layout tweaks.
  316.  
  317.  
  318. 2.1b1    30 April 1998
  319.  
  320. First public release.
  321.  
  322.  
  323.  
  324. Last modified 98/04/29
  325. Simon Fraser sfraser@netscape.com
  326.  
  327.